COMMENT ⊗   VALID 00011 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	.NEWSEC THE BASIC SOURCE LANGUAGE
C00003 00003	.NEWSS DATA STRUCTURES
C00012 00004	.NEWSSS VECTORS
C00017 00005	.NEWSSS ROTATIONS
C00020 00006	.NEWSSS FRAMES
C00024 00007	.NEWSSS PLANES
C00028 00008	.NEWSSS TRANSFORMS
C00032 00009	.NEWSSS PLANNING VALUES
C00037 00010	.arith: NEWSSS	ARITHMETIC
C00041 00011	.NEWSSS	SOME EXAMPLES OF ARITHMETIC EXPRESSIONS
C00043 ENDMK
C⊗;
.NEWSEC THE BASIC SOURCE LANGUAGE

'AL has several levels of complexity.  We will start by discussing the
basic source language; this covers enough to write substantial
manipulator programs, but has none of the high level capabilities 
mentioned in the section on goals and philosophy.

.NEWSS DATA STRUCTURES
.DAT:NEWSSS DATA TYPES

	In this section we present the data types available in
'AL.  Roughly speaking, a %4data type%* is a kind of numeric object.
For example, FORTRAN has the data types INTEGER and REAL.  A %4variable%*
is an identifier of some type 
which can take on %4values%*.  In 'AL, each variable must
be %4declared%*, that is, one must state what its type is,
somewhere in the program before it is used.
There are several reasons for this:
It allows the compiler to detect spelling errors,
and it allows the same name to be used in different blocks without
conflict.  'AL uses ALGOL block structure,
which means that all variables declared between a particular BEGIN and
END are accessible only to code which appears between the same BEGIN-END
pair. The exact details of block structure are discussed in the section
on control structures.

.NEWSSS	ALGEBRAIC DATA TYPES: SCALARS

	Algebraic data types are the most familiar.  They represent
measurements in the real world.  An algebraic variable can assume
a value by means of the %4assignment statement%*, which consists
of the variable name, a left arrow ("α←"), and an expression which has the
correct type.
When an assignment statement is executed, the expression on the right
hand side is evaluated, and that value replaces the old value of the
variable on the left hand side.

	The most elementary data type is  %4scalar%*,   which is  internally
represented  as  a floating-point  number.   Scalars  are  used 
for dimensionless quantities, like the number of times some operation
is to be repeated, or to implement a  signal which becomes positive when some
critical operation is finished.
The arithmetic operations available on scalar variables are addition,
subtraction, multiplication, and division; the arithmetic operators which
perform these operations are the standard: +, -, *, /.  As is usual in
algebraic languages, the first two have lower precedence than the  others.

	Scalar constants are written as (base ten) numbers, either with
or without a decimal point and fractional part.
Here are some examples of declarations and applications of scalar variables:
.unfill
	SCALAR s1, s2;
.COMT 12
		 α{Our examples will use a mnemonic
		scheme for naming variables to clarify the
		type of each entity.  Please understand that 
		identifiers can be any string of letters, of any 
		length, and that 'AL does not distinguish between
		upper and lower case.  Curly brackets are used in
		'AL to enclose comments.α}
.END
	s1 ← 2;
	s2 ← 3.74;
	s1 ← s2 * (s1 - 3.2);
.REFILL

	It is often desirable to give some physical meaning to scalar
variables.  'AL provides for scalars with the dimensions %4time,
distance, angle,%* and %4mass%* in addition to "simple",
dimensionless scalars.  Time constants are just like simple scalar
constants, except they are multiplied by the reserved word %4sec%*
(for "seconds").  The other reserved words related to these
dimensioned scalars are %4cm%* (centimeters), %4deg%* (degrees) and
%4gm%* (grams). 

	Dimensioned scalars are used exactly in the same way
as simple scalars; the only difference is that 'AL will check 
that addition and subtraction are only performed on compatible values.
'AL performs dimension checking for each arithmetic operation and
each assignment.  Addition, subtraction, and assignment require exact
dimension match,
but if match fails and one of the two arguments is simple (no dimension),
it will be converted.  Thus it is always legal to use simple scalars
where dimensioned ones are expected.
Multiplication and division do not
require dimension match; they
produce a result
of a dimension usually different from that of the arguments; this new dimension
is then propagated through the expression.  In this way, intermediate
results can be of dimensions not declared.  This causes no problem unless
one tries to use such results in an assignment.


	Here are some examples of dimensioned scalars:
.UNFILL
	TIME SCALAR tm1, tm2;
	MASS SCALAR ms1;
	ANGLE SCALAR theta, phi;

	tm1 ← 3 * SEC;
	ms1 ← ms1 + 2.2 * GM;
	ms1 ← ms1 + 2.2;  
.COMT 12
		α{The constant 2.2 will be automatically
		converted to grams.α}
.END
	theta ← 90 * DEG;
	tm1 ← tm2 * 5.5;
	phi ← theta * 4 * DEG;  
.COMT 12
		α{This is a mistake;
		the right side has dimension %*angle*angle%4α}
.END
.REFILL

	If the user feels more comfortable with inches or pounds, it
is quite easy to write macros which will make such usage possible.
This is best demonstrated by example:
.UNFILL
	DEFINE INCHES = "(2.54 * CM)";
	DEFINE FEET = "(12 * INCHES)";
	DEFINE LB = "(GM * 1000 / 2.2)";

	ms1 ← 2.2*LB;  α{= 1000*GMα}
	ds1 ← 3*FEET;  α{= 3*12*2.54*CMα}
.REFILL

	The user may wish to create new dimensioned scalars, such
as forces or velocities.  This is readily done by means of the
%4dimension%* statement and a few macros.  For instance,
.UNFILL
	DIMENSION FORCE = DISTANCE*MASS/(TIME*TIME);
	DEFINE DYNES = "(GM*CM/(SEC*SEC))";
	DIMENSION VELOCITY = DISTANCE/TIME;
	DEFINE CPS = "(CM/SEC)";

	FORCE SCALAR fo1;
	VELOCITY SCALAR ve1;
	ve1 ← 2.3*CPS;
	fo1 ← ve1 * 3 * GM / (8.4 * SEC);
.REFILL

Please note that the DIMENSION statement and macros follow block
structure; it is a good idea to put them in the outermost block.

.NEWSSS VECTORS
	Scalars are insufficient to describe all measurements of interest
to the user of 'AL.  We turn now to other algebraic
data types.  They are syntactically much like scalars:  they are declared
and can enter into arithmetic expressions and assignments.

	The world in which 'AL resides has three dimensions.
We impose a Euclidean structure on that space by setting up three
cardinal, orthogonal axes, which meet at the origin.
The actual alignment of these %4station%* axes will, in general, depend
on the particular work station involved; it is expected, however,
that the positive Z axis will point upwards (this is not at all
crucial).

	The first data type we will discuss is the %4vector%*.  It represents
either a translation or a location.  The latter 
meaning is the result of
translating the null vector, that is, the origin of the coordinate system.
As is the case with scalars, vectors may be dimensioned.

	Vectors can be constructed from three scalar expressions
by means of the function VECTOR.
The scalar expressions must all be of the same dimension, and the resulting
vector has that same dimension.

Addition and subtraction are defined on vectors of the same dimension.
One other function is available: the dot product.  For example, if
the two vectors are:
.UNFILL
	v1=VECTOR(x1,y1,z1) and v2=VECTOR(x2,y2,z2),

then we have

	s * v1 = VECTOR(s*x1, s*y1, s*z1)
	v1 + v2 = VECTOR(x1+x2, y1+y2, z1+z2)
	v1 - v2 = VECTOR(x1-x2, y1-y2, z1-z2)
	v1 . v2 = x1*x2 + y1*y2 + z1*z2    .
.REFILL

Thus, addition
and subtraction produce vectors in the familiar way; the dot product
is the sum of the products of the three components; its dimension
is the product of the dimensions of the two arguments.

It is possible to "stretch" or "shrink" vectors by multiplying and
dividing them by scalars.
The dimension of the resulting vector is the product or the quotient
of the dimensions of the two arguments. 
The magnitude of
a vector is calculated by the function ABS, which returns
a scalar of appropriate dimension.

	There are several predeclared vectors in 'AL:
.UNFILL
	VECTOR X, Y, Z, NILVEC;
.COMT 12
	α{These are predeclared and have values as followsα}
.END
	X ← VECTOR(1,0,0);
	Y ← VECTOR(0,1,0);
	Z ← VECTOR(0,0,1);
	NILVEC ← VECTOR(0,0,0);
.REFILL
The components of a vector can be easily extracted as the dot
product of the vector with X, Y, or Z.
Here are examples of other vectors:
.UNFILL
	VECTOR v1;
	DISTANCE VECTOR dv1, dv2;
	SCALAR s1;
	DISTANCE SCALAR ds1, ds2;

	ds1 ← 4 * CM;
	s1 ← -2;
	dv1 ← VECTOR(s1, 2.3, ds1);
.COMT 12
	α{This is a distance vector; the simple scalars get converted.α}
.END
	ds2 ← dv1 . Y;  α{%4So ds2 gets 2.3*CM%*α}
	v1 ← dv1 / ds2;  α{%4So v1 ← VECTOR(-2/2.3, 1, 4/2.3)%*.}
	dv2 ← ds2 * v1;  α{%4So v2 ← dv1%*α}
	s1 ← ABS(v1);
.REFILL

.NEWSSS ROTATIONS

	The %4rot%*, our next data type,
represents either a rotation or an orientation.
The latter is the result of applying the
rotation to the station coordinate system.
Rots are internally stored as 3x3 matrices, which operate on
column vectors in the usual way.  Thus
rots can operate on vectors and move them around
the origin (without changing their length); they can also operate
on other rots (by matrix multiplication).
To rotate a vector (about the station origin), multiply
the vector (on the right) by the rot (on the left).  To compose
rots, multiply them together; the one on the right will be
applied first.

A rotation can be constructed with the function ROT, which takes
two arguments:  a simple vector, which is to be the axis of rotation, and 
an angle, which is the amount to rotate.
The direction of rotation follows the right-hand rule; a rotation
of 90 degrees about the X axis moves the Y axis into the Z axis.
This turns out to be a general representation far easier to
write and understand than raw matrices.  We hope the following
examples will serve to clarify the proper use of rots:
.UNFILL
	ROT r1, r2, r3;
	ANGLE SCALAR alpha, beta, gamma;
	r1 ← ROT(X, 90*DEG);
	v1 ← r1 * Z;  
.COMT 12
		α{V1 gets Z rotated 90 degrees about X, so V1 α← VECTOR(0,-1,0).α}
.END
	r2 ← ROT(Y, 45*DEG);
	r3 α← r2 * r1; 
.COMT 12
	    α{Thus, r3 means:  rotate first 90 degrees about the X axis,
		then 45 about the original Y axis.α}
.END
.MAYBREAK

	r1 ← ROT(X,alpha);
	r2 ← ROT(r1*Y,beta);
	r3 ← ROT(r2*Z,gamma);
	r4 ← r3 * r2 * r1;
.COMT 12
		α{r4 is then a rotation with this meaning:
		Rotate by alpha degrees about the X axis, then by
		beta degrees about the new Y axis, then by gamma
		degrees about the doubly new Z axis.α}
.END
.REFILL
The null rot, which has no effect, is called NILROT.

.NEWSSS FRAMES

	The next data type is the %4frame%*, used to represent a
coordinate system.  It has two components: the location of the origin
(a distance vector) and the orientation of the axes (a rot).  Frames
are typically used to describe objects; one can specify locations of
features on an object by translating them from the object's origin. 

	There are several predeclared frames in 'AL.  %4Station%*
is the frame which represents the work station's frame of reference.
Each hand available to the system also has a frame variable, whose
value (continually updated)
is the position of that hand.  Currently, there are two such
frames:  %4yellow%* and %4blue%*.  Each arm has a rest, or
park position, known as %4ypark%* and %4bpark%*.

	A frame may be constructed by a call 
on the function FRAME:
.UNFILL
	FRAME f1;
	DISTANCE VECTOR dv1;
	ROT r1;
	:
	f1 ← FRAME(r1,dv1);
.REFILL
The two arguments are a a rot (for the orientation) and a distance
vector (for the position).  To extract the rot or the vector from a
frame, use the functions ORIENT and LOC, respectively.  To find where
a vector goes if its base is moved from the station to the coordinate
system of some frame, "multiply" the frame (on the left) by the
vector (on the right).  
To translate a frame by some distance, simply add a distance vector to it.

Often one wants to construct a vector which
is oriented like some vector (for example, the X vector) in some
frame, say F1.  The %4with respect to%* operator %4WRT%* gives
exactly that; one writes (X#WRT#F1).  Examples of this and other
constructs pertaining to frames follow: 
.UNFILL
	FRAME f1, f2;
	f1 ← FRAME(ROT(Z,90*DEG),2*X);
.COMT 12
		α{f1 sits 2 centimeters from the station, in the X
		direction.  Its coordinate system has X where the
		station's Y points.α}
.END
	v1 ← X WRT f1;  α{%4This evaluates to VECTOR(0,1,0).%*α}
	f2 ← f1 + v1;  α{%4Just like f1, but with origin at (2,1,0).%*α}
	v1 ← f1 * Y;  α{%4This evaluates to VECTOR(1,0,0)%*α}
	v2 ← v3 WRT f2;  
.COMT 12
	α{This is equivalent to (f2*v3) - LOC(f2), and also to
	ORIENT(f2)*v3.α}
.END
.REFILL

.NEWSSS PLANES

	Next we have the %4plane%*, used to separate space into regions and
to specify the locus of searches.  Planes are formed by use of the
function PLANE, which takes two distance vectors as arguments:  The plane
is to pass through the first vector, and the outward-facing normal
to the plane is in the direction of the second vector.  
Thus PLANE(X,Y) is a plane parallel to the X-Z plane, translated
from it by one centimeter in the X direction.

Planes are internally stored by four numbers: the first three 
are an outward-facing normal, and the last is the opposite of the
distance from the plane to the origin.  

Each plane divides space into three regions: inside, on, and outside
the plane.  (The last set contains all points on the same side as 
outward-facing normal.) To find out
in which region a point (represented by a distance vector) lies,
extract the inner product of the vector with the plane.  Its value is
a distance scalar whose absolute value is the shortest distance from
the vector to the plane, and whose sign is negative if the vector is
inside the plane, 0 if the vector is on the plane, and positive if
the vector is outside the plane.  The arithmetic operator for the
inner product is a dot; the plane may appear on either side of the dot.
If the plane P has an internal
representation consisting of four numbers A, B, C, and D,
and V#=#VECTOR(X1,Y1,Z1),
 then we have:
.UNFILL
	P . V = A*X1 + B*X2 * C*X3 + D
.REFILL

Other operations available on planes are translation (by adding a
distance vector) and rotation (by multiplying by a rotation).  To get
the outward-facing normal of a plane, use the function NORMAL, which
takes a plane argument and returns a distance vector. 

Examples:
.UNFILL
	PLANE p1, p2;
	p1 ← PLANE(VECTOR(0,0,0),Z);
.COMT 12
		α{This is the surface of the stationα}
.END
	v1 ← NORMAL(p1 + v2);
.COMT 12
		α{No matter what v2 is, v1 will get Zα}
.END
	ds1 ← p1 %5.%* VECTOR(2, -13.2, 32.3);
.COMT 12
		α{ds1 gets 32.3*cmα}
.END
.REFILL

.NEWSSS TRANSFORMS

	The last of the algebraic data types is the %4trans%*, which
stands for "transform".  It is an operator, that is, a function, which
can operate on vectors, frames, and planes.  The application of a
trans to any of these is written as if it were a multiplication, with
the trans on the left.  To compose several transes together, "multiply"
them, with the one to be applied first on the right.

	The trans itself is defined as a function which can take objects
in one frame of reference into another.  One can construct a trans
by use of the function TRANS:
.UNFILL
	TRANS t1;
	VECTOR v1;
	ROT r1;
	:
	t1 ← TRANS(r1,v1);
.REFILL
The two arguments are a rotation the rotational part and a vector
(the translational part).  The
application of a trans to a vector, frame, or plane first rotates that
object according to the rotation part (rotating about the station origin),
and then translates the result according to the translational part.

Transes, like vectors and scalars, carry dimension.  The rule is that
when a trans is applied to a vector, they must agree in dimension; the
resulting vector is of the same dimension.  When a trans is applied to a
frame, it must be a distance trans.  When a frame is used in a
context demanding a transformation, it will be understood as a
shorthand for the distance trans leading from the station.  When
transes are composed, they must agree in dimension.

	There is another convenient way to specify a trans: by forming
it from two frames.  The trans is then the function which takes the
origin of the first frame across to the origin of the second, performing
a rotation first to get the axes aligned.  This method of specifying
a trans is accomplished by use of the arithmetic operator "α→".

	Examples:
.UNFILL
	TRANS t1, t2;
	t1 ← f1 → f2; α{%4Thus t1*f1 = f2%*α}
	v1 ← t1 * v2;
	t2 ← t1 * t1;
	v1 ← f1 * v2;  α{%4Equivalent to (STATION→f1)*v2%*α}
.REFILL

The null trans, equivalent to TRANS(NILROT,NILVEC) is called NILTRANS.

.NEWSSS PLANNING VALUES

	'AL works under the fundamental philosophy that arm motions
should be planned in advance.  Since an arm trajectory cannot be
calculated reasonably unless the end-points (and any specified
intermediate points) are known fairly accurately, it is necessary
that the compiler maintain for each variable a %4planning value%*
which may be used in the case that the variable enters into a motion
specification.  Planning values are discussed in more detail in
{ssref pvs}. 

Essentially, the compiler attempts to assign to each variable a
planning value for each statement in the program.  Initially, the
planning value of each variable is "undefined"; one of the ways that
a planning value can be assumed is through an assignment statement.
The compiler evaluates the planning value of the right hand side, and
this becomes the new planning value of the variable on the left. 
Propagating the planning value across loops is complicated; in the
case that the variable can take multiple values, the compiler either
sets the planning value to "undefined" or, as 'AL becomes more
advanced, maintains parallel "worlds" in which each planning value is
monovalued. 

	Variables can attain different values at run-time than their
planning values when some real-world measurement is taken and the
result used in an arithmetic expression.  The most common example of
this is that the frames %4yellow%* and %4blue%* are always kept accurate at
run-time by feedback from the arm hardware, so their values will in
general differ from those planned. 

.arith: NEWSSS	ARITHMETIC

	Here is  a summary of  the arithmetic  expressions available.
They  are grouped by the  type of their values.   These abbreviations
are used: `s' = scalar, `v' = vector, `r' = rot, `f' = frame, `p' = plane,
`t' = trans.
%7
.BEGIN VERBATIM
.GROUP

scalar expressions:
s + s		scalar addition (commutative)
s - s		scalar subtraction
s * s		scalar multiplication (commutative)
s / s		scalar division
v . v		dot product of two vectors (commutative)
p . v		signed distance from vector to plane (see discussion
			above on planes)
v . p		signed distance from vector to plane (see discussion
			above on planes)

.MAYBREAK
vector expressions:
s * v		dilation of a vector
v / s		contraction of a vector
v + v		vector addition (translation of the first vector by 
			the second) (commutative)
v - v		vector subtraction
r * v		rotation of a vector
t * v		transformation of a vector
v WRT f		a vector of length ABS(v) rotated into f's system; like
			ORIENT(f)*v; that is, a vector in station
			coordinates which looks to the station as v
			does to f.
.MAYBREAK
rot expressions:
r * r		composition of two rots (first to be applied is on the 
			right)

.MAYBREAK
frame expressions:
f + v		translation of a frame
t * f		transformation of a frame

.MAYBREAK
plane expressions:
p + v		translation of a plane by a vector
r * p		rotation of plane (about station origin)
t * p		transformation of a plane by a trans

.MAYBREAK
trans expressions:
f → f		transformation which leads from the first frame to
			the second
t * t		composing two transes.  The one on the right will 
			operate first.

.END
.UNFILL

%1PREDECLARED CONSTANTS AND VARIABLES:

π is simple, has value = 3.14159...
STATION is a frame which has standard station coordinates. (constant)
BLUE is the location of the blue hand.
YELLOW is the location of the yellow hand.
BPARK is where the blue hand parks. (constant)
YPARK is where the yellow hand parks. (constant)
X is VECTOR(1,0,0).
Y is VECTOR(0,1,0).
Z is VECTOR(0,0,1).
NILVEC is VECTOR(0,0,0).
NILROT is ROT(X,0*DEG).
NILTRANS is TRANS(NILROT,NILVEC).

.maybreak
EXTRACTION FUNCTIONS:

LOC(FRAME) is a vector whose value is the location of the frame.
ORIENT(FRAME) is a rot whose value is the orientation of the frame.
NORMAL(PLANE)	is the outward facing normal vector of a plane.
.REFILL

.NEWSSS	SOME EXAMPLES OF ARITHMETIC EXPRESSIONS
.SELECT 1
.UNFILL
In the following examples, assume these declarations:
FRAME f1, f2, etc;
VECTOR v1, v2, etc;
SIMPLE s1, s2, etc;
ROT r1, r2, etc;
PLANE p1, p2, etc;

.MAYBREAK
f1'S unit Y vector, in station coordinates:
	f1 * Y

.MAYBREAK
f1's Z vector as seen from f2:
	(f2 α→ f1) * Z

.MAYBREAK
A vector pointing in same direction as f1's X coordinate:
	X WRT f1

.MAYBREAK
v1 rotated 90 degrees about the station's Z axis:
	ROT(Z,90*DEG)*v1

.MAYBREAK
f1's Y-Z plane:
	PLANE(LOC(f1),X WRT f1)

.MAYBREAK
A plane 3 centimeters above the station:
	PLANE(VECTOR(0,0,3),Z);
	PLANE(3*Z,Z);

.MAYBREAK
An identity with WRT:
	v1 WRT f1 = ORIENT(f1)*v1 = (f1*v1) - LOC(f1)
.REFILL